Extra functions

This section describes extra PKCS#11 functions.

CT_SetHsmDead

This function can be used by an application to simulate the behavior of the WLD or HA system when an HSM fails. See also CT_GetHSMId.

Synopsis

CK_DEFINE_FUNCTION(CK_RV, CT_SetHsmDead)(
        CK_ULONG hsmIDx, 
        CK_BBOOL bDisable
);

This function is a SafeNet extension to PKCS#11.

CT_GetHSMId

This function can be used to identify the HSM that a particular WLD or HA session has been assigned to.

This function is a SafeNet extension to PKCS#11.

Synopsis

CK_DEFINE_FUNCTION(CK_RV, CT_GetHSMId)(
        CK_SESSION_HANDLE hSession,
        CK_ULONG_PTR pHsmid
);

CT_ToHsmSession

This function can be used to convert the Cryptoki session handle seen by the application into the session handle used by the HSM.

Synopsis

CK_DEFINE_FUNCTION(CK_RV, CT_ToHsmSession)(
    CK_SESSION_HANDLE hSessionApp,
    CK_SESSION_HANDLE_PTR phHsmSession
);

This function is a SafeNet extension to PKCS#11.

FMSC_SendReceive

This is an extended function supporting custom Functionality Module (FM) calls through Cryptoki. Previously, PKCS-patched FMs were invoked through the Cryptoki interface while Custom FMs were invoked through the Message Dispatcher interface (ETHSM). With this new API, custom FMs can be called directly through the Cryptoki interface. Also, custom FM calls can now use features such as:

• Secure Messaging System - requests are sent/received in encrypted form

• High Availability/Work Load Distribution - WLD can now be used with FMs

Synopsis

CK_RV FMSC_SendReceive(
    CK_SESSION_HANDLE hSession,
    CK_USHORT fmNumber,
    CK_BYTE_PTR pRequest,
    CK_ULONG requestLen,
    CK_BYTE_PTR pResponse,
    CK_ULONG responseLen,
    CK_ULONG_PTR pReceivedLen,
    uint32 *pfmStatus
);

Header file

ctfext.h

Parameters

hSession

Session handle to be associated with the request.

fmNumber

Identifies the FM number this message is intended for. Make sure it matches the FM number defined in the FM application.

pRequest

Pointer to request buffer.

Note

If you are using ProtectToolkit 7.2.0 or newer with ProtectServer 3 HSM Firmware 7.02.00 or newer, the combined buffer size of pRequest and pResponse cannot be greater than approximately 64 MB. However, if the data size is greater than approximately 64 KB, the message transfer is slower than if it is less than 64 KB. For best efficiency, keep all messages less than 64 KB in size.

If you are using ProtectToolkit 7.1.0 or older with ProtectServer 3 HSM Firmware 7.01.01 or older, the buffer size of pRequest cannot be greater than approximately 64 KB.

prequestLen

Number of bytes in the request.

pResponse

When the function returns, the response from the FM is contained in these buffers.

Note

If you are using ProtectToolkit 7.2.0 or newer with ProtectServer 3 HSM Firmware 7.02.00 or newer, the combined buffer size of pResponse and pRequest cannot be greater than approximately 64 MB. However, if the data size is greater than approximately 64 KB, the message transfer is slower than if it is less than 64 KB. For best efficiency, keep all messages less than 64 KB in size.

If you are using ProtectToolkit 7.1.0 or older with ProtectServer 3 HSM Firmware 7.01.02 or older, the buffer size of pResponse cannot be greater than approximately 64 KB.

responseLen

Length of the initialized response buffer in bytes

pReceivedLen

Actual length of response received from the FM.

pfmStatus

Status code returned by the FM.

In addition to the standard PKCS#11 and extended function codes, the function can return:

Refer to FM SDK programming for a full description of FM development. A sample is provided along with the FM SDK to demonstrate the function of this API.